.TH lha_buildapp 1 "6 February 2009" "TrueCL Commands"

.SH NAME
lha_buildapp \- Build or Change Application Configuration

.SH SYNOPSES
.TS
l l.
clreq	\fB-A|--application\fP \fIX\fP [\fB--startscript\fP \fIS\fP] [\fB--stopscript\bP \fIS\fP]
	[\fB--starttimeout\fP \fIN\fP] [\fB--stoptimeout\fP \fIN\fP] [\fB--nodes\fP \fI[+|-]node,...\fP]
	[\fB--vg\fP \fI[+|-]vg,...\fP] [\fB--storage\fP \fIdrbd1|drbd82|nfs|shared\fP]
	[\fB--consistency\fP \fInormal|force\fP] [\fB--topology\fP \fIT\fP] [\fB--syncrate\fP \fIN\fP]
	[\fB--fs\fP \fI[+|-]mntpnt[:vg:lv:fstype:opts],...\fP]
	[\fB--ip\fP \fI[+|-]ip:network[:netmask=y,broadcast=z]\fP] [\fB-timeout\fP \fIN\fP]
	[\fB--force\fP] [\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP]
	[\fB--lwidth\fP \fIN\fP]
.TE

.SH DESCRIPTION
The \fIlha_buildapp(1)\fP command is used to build new applications, and change existing
ones. It takes a large range of parameters, some of which must be specified and used during the
application build before others. 

\fBIT IS RECOMMENDED THAT THE ADMINISTRATORS GUIDE IS REFERRED TO BEFORE USING THIS COMMAND.\fP

The only parameter that always must be present is the one that specifies the application. Not all
applications require all parameters to be defined, and many of the parameters are not strictly
necessary unless the application being defined has certain characteristics.

As with all TrueCL commands the commands can be run on any node. However it often makes sense
when initially defining the application to mount he file systems being used on one of the nodes
and define the application from there - this is because it allows TrueCL to clean to file system
types and mount options automatically rather than you having to provide them.

.SH ARGUMENTS
.TP 8
--application
This is the name of the application to create or update. Multiple \fIlha_buildapp(1)\fP
commands can be used to used to define the application, so the command will obviously
work if the application is defined already.

If this is a new application there are two parameters that are expected to be used
to define the storage during the initial application configuration that takes place:

.TP
--storage
This indicates the type of storage that the application is using. An application can only
use one type of storage, though different applications can use different types of storage
in the same cluster if you wish.

There are currently 4 types of storage types defined:

.RS 8
.TP 8
drbd1
This is deprecated now; though should still work. It is a Linux-only solution
suitable for storage replication over IP between two nodes. Each node has a 
local copy of the data; no expensive dual-attached storage is necessary.
.TP
drbd82
If you wish to use replicated storage between two Linux nodes then this is
the preferred option. It is based on drbd 8.2 [see www.drbd.org for details].
Since this is a replicated solution no expensive dual-attached storage is
necessary.
.TP
nfs
If an application wishes to make use of nfs to store its data then this type
should be used. It differs from the other storage types because it does not
get deactivated/unmounted when an application is stopped, or activated/mounted
when the application is started. This allows it to be present on multiple nodes at the 
same time.
.TP
shared
This should be used whenever the storage in question is the same physical storage
mapped to the nodes in the cluster. TrueCL will activate/deactivate access to this
storage on a per-node basis depending on which node is running the application at
any one time.
.RE

\fBThe storage type is not related to the Volume Manager in use\fP. For example in 
Linux LVM is used for all the above storage types.

.TP
--vg
This defines the volume groups that the application will use. Only one application can
use a particular volume group name across the cluster - this will be checked and the
change rejected if it does already exist elsewhere.

This can be a comma-separated list and the volume groups can [if you wish] be active on the
current machine where the application is being created for. 

The list can be preceded with a '+' - and in this instance the list of volume groups 
given is added to any existing list [duplicates being automatically removed]. If the list 
beings with a '-' it will remove the specified list of volume groups defined for the
application if they are currently defined.

When a volume group is removed from the application configuration any associated file systems
are also removed. If the application is currently running those file systems will be 
un-mounted and the disk group deactivated, though no data which actually be deleted.

.TP
--nodes

.TP
--startscript
Indicates the script to run when the application is to be started on the node. Please note that
this is run as root once all storage for the application is active and so can reference
the storage used for the application if necessary.

.TP
--stopscript
The script used to stop the application. This is run as root and is run whilst all the storage
is active. Once this script completes all remaining processes using the storage associated
with the application will be killed off to ensure the storage can be deactivated where 
appropriate.

.TP
--starttimeout

.TP
--stoptimeout

.TP
.TP
--force
If any nodes that should be part of the cluster are not currently contactable via 
the request daemons then any attempt to use \fIlha_buildapp(1)\fP will fail by default.
To force through the change without being able to contact all nodes use this argument.

It should be noted that this is not recommended since it can lead to inconsistent cluster
configurations across the nodes. 
.TP
--timeout
The amount of time to wait for certain responses to requests that are 
necessary for the application to be stopped.  If this is not specified it will
default to 10 [seconds].
.TP
--debug
Run the application modification in 'debug' mode - might produce significant levels 
of output to the standard output device, most of which is only useful for
developers.
.TP
--verbose
Verbose mode generates a sensible amount of output to standard output to 
show the progress of application modification. This is the recommended flag if
the administrator wishes to see any output.
.TP
--quiet
This will only produce errors and warnings on the standard output device.
.TP
--silent
Only produce output if fatal errors occurs during attempted change of the 
application status.

.SH OUTPUT
None of the output modes generates anything really lengthy. Typically this 
command completes in less than a second and so feedback via the \fB--verbose\fP
option is not typically needed.

.SH EXIT CODES
If the application status is changed as expected, a return code of '0' will be given, 
indicating success. Otherwise a failure is indicated with a return code of '1'.
If a failure does occur then a suitable error message should be shown on the
standard output device too.

.SH FILES
The utility uses the cluster request daemons to handle all changes. Hence any 
changes, problems or errors will be found in the log files for that
daemon, available on each node in the cluster. 

.TS
l l.
clreqd.log	Standard log file for messages.
clreqd.stdout	Will contain any standard output text for the application.
clreqd.stderr	Will contain any error output text for the application.
.TE

.SH NOTES
Remember all settings only exist whilst the cluster is running. If the cluster is
stopped and restarted any changes will be lost and settings will return to default.

.SH AUTHOR
The TrueCL software was written by Simon Edwards, (C) 2006-2008, working
for Advantsys Computer Services Ltd - www.advantsys.co.uk.

.SH SEE ALSO
.BR lha_app_probes(1),
.BR lha_app_routes(1),
.BR lha_buildapp(1),
.BR lha_destroyapp(1).

.SH AVAILABILITY
This utility was specifically written under the GNU GPL license and as required
by such software comes with \fIno warranty or guarantee of any kind\fP. For
more information, please see the following page: truecl.advantsys.co.uk.

